Metona 内部 API 请求与响应标准

export interface MetonaThinking {
  /** 思考内容文本 */
  content: string;

  /** 思考状态 */
  status: 'thinking' | 'complete';

  /** 思考耗时 (ms) */
  durationMs: number;

  /** 思考消耗的 token 数 */
  tokensUsed: number;
}

export interface MetonaToolCall {
  id: string;                      // 工具调用唯一 ID
  name: string;                    // 工具名称
  args: Record<string, unknown>; // 调用参数
  iteration: number;              // 所属 ReAct 迭代
  timestamp: number;
}

export interface MetonaToolResult {
  toolCallId: string;
  toolName: string;
  result: unknown;               // 工具原始返回值
  summary?: string;              // 人工可读摘要（用于 LLM 上下文注入）
  success: boolean;
  error?: string;
  durationMs: number;
  timestamp: number;
}

export interface MetonaError {
  code: MetonaErrorCode;          // 错误码
  message: string;               // 人类可读的错误描述
  provider?: string;              // 出错的 Provider
  providerCode?: string;         // Provider 原始错误码
  retryable: boolean;            // 是否可重试
  retryAfterMs?: number;        // 建议重试等待时间
}

export enum MetonaErrorCode {
  // 网络层
  NETWORK_TIMEOUT = 'network_timeout',
  NETWORK_ERROR = 'network_error',

  // 认证层
  AUTH_INVALID = 'auth_invalid',
  AUTH_EXPIRED = 'auth_expired',

  // 频率限制
  RATE_LIMITED = 'rate_limited',
  QUOTA_EXCEEDED = 'quota_exceeded',

  // 模型层
  MODEL_OVERLOADED = 'model_overloaded',
  MODEL_NOT_FOUND = 'model_not_found',
  CONTEXT_LENGTH_EXCEEDED = 'context_length_exceeded',
  OUTPUT_LENGTH_EXCEEDED = 'output_length_exceeded',

  // 内容层
  CONTENT_FILTERED = 'content_filtered',

  // 解析层
  PARSE_ERROR = 'parse_error',
  INVALID_RESPONSE = 'invalid_response',

  // Agent 层
  MAX_ITERATIONS = 'max_iterations',
  USER_ABORTED = 'user_aborted',
  TIMEOUT = 'timeout',
  UNKNOWN = 'unknown',
}

export interface MetonaContext {
  /** 上下文唯一标识 */
  id: string;

  /** 关联的会话 */
  sessionId: string;

  /** System Prompt 分区 */
  systemPrompt: MetonaSystemPrompt;

  /** 会话历史（最近 N 轮） */
  history: MetonaMessage[];

  /** 检索到的相关记忆 */
  relevantMemories: MetonaMemoryItem[];

  /** 当前任务信息 */
  currentTask: {
    userInput: string;
    iteration: number;
    taskGoal?: string;
  };

  /** 可用工具列表 */
  availableTools: MetonaToolDef[];

  /** 预估 Token 数 */
  estimatedTokens: number;

  /** 上下文使用率（estimatedTokens / contextWindow） */
  usageRatio: number;

  /** 是否需要压缩 */
  needsCompression: boolean;
}

export interface MetonaMemoryItem {
  id: string;
  type: 'episodic' | 'semantic' | 'working';

  /** 可被 LLM 阅读的记忆内容 */
  content: string;

  /** 精简摘要（上下文紧张时使用） */
  summary?: string;

  /** 来源 */
  source: 'user_input' | 'tool_result' | 'agent_thought' | 'imported';

  /** 重要程度 0-1 */
  importance: number;

  /** 检索相关性分数（仅在检索结果中出现） */
  relevanceScore?: number;

  sessionId?: string;
  createdAt: number;
  expiresAt?: number;
}

export interface IMetonaProviderAdapter {
  /** Provider 标识 */
  readonly providerId: string;

  /** 支持的模型列表 */
  readonly supportedModels: string[];

  /** 上下文窗口大小 */
  getContextWindow(model: string): number;

  /** 健康检查 */
  healthCheck(): Promise<boolean>;

  /**
   * 核心方法：发送请求
   * @param request - Metona 标准请求
   * @returns Metona 标准响应
   */
  send(request: MetonaRequest): Promise<MetonaResponse>;

  /**
   * 核心方法：发送流式请求
   * @param request - Metona 标准请求
   * @param onEvent - 流式事件回调
   * @returns 完整响应（流结束后返回）
   */
  sendStream(
    request: MetonaRequest,
    onEvent: (event: MetonaStreamEvent) => void
  ): Promise<MetonaResponse>;

  /** 获取可用模型列表 */
  listModels(): Promise<MetonaModelInfo[]>;
}

export interface MetonaModelInfo {
  id: string;
  providerId: string;
  displayName: string;
  contextWindow: number;
  maxOutput: number;
  supportsStreaming: boolean;
  supportsThinking: boolean;
  supportsImages: boolean;
  supportsToolCalling: boolean;
  supportsStructuredOutput: boolean;
  pricing?: MetonaPricing;
}

export interface MetonaPricing {
  inputPerMillion: number;
  outputPerMillion: number;
  currency: string;
}

// ===== Agent Loop 构造 =====
const request: MetonaRequest = {
  meta: { sessionId: 's_abc', iteration: 1, requestId: 'r_001', timestamp: Date.now(), agentVersion: '1.0.0' },
  systemPrompt: {
    roleDefinition: '你是一个专业的编程助手。',
    outputConstraints: '用中文回答，代码块使用 ``` 包裹。',
    safetyGuidelines: '不编造事实，不确定时如实说明。',
  },
  messages: [
    { role: 'user', content: '解释 JavaScript 的事件循环机制。', timestamp: Date.now() },
  ],
  params: { maxTokens: 4096, temperature: 0.0, stream: false, thinkingEnabled: false },
};

// ===== Adapter 返回 =====
const response: MetonaResponse = {
  meta: { requestId: 'r_001', provider: 'deepseek', model: 'deepseek-v4-pro', latencyMs: 850, timestamp: Date.now() },
  content: 'JavaScript 的事件循环（Event Loop）是...\\n\\n```js\\nconsole.log(1)...\\n```',
  usage: { inputTokens: 120, outputTokens: 350, totalTokens: 470 },
  finishReason: MetonaFinishReason.STOP,
};

// ===== 第 1 轮：Agent 发送请求，LLM 返回工具调用（流式） =====
const request1: MetonaRequest = {
  meta: { sessionId: 's_xyz', iteration: 1, requestId: 'r_002', timestamp: Date.now(), agentVersion: '1.0.0' },
  systemPrompt: { /* ... */ },
  messages: [
    { role: 'user', content: '读取 /home/user/data.csv 并分析内容。', timestamp: Date.now() },
  ],
  tools: [
    { name: 'read_file', description: '读取文件内容', /* ... */ },
    { name: 'analyze_csv', description: '分析 CSV 数据', /* ... */ },
  ],
  params: { stream: true, thinkingEnabled: true },
};

// 流式事件：
// → thinking_start → reasoning_delta ... → thinking_end
// → tool_call_complete { id: 'tc_1', name: 'read_file', args: { file_path: '/home/user/data.csv' } }
// → done

// ===== Agent Loop 执行工具后，构造第 2 轮请求 =====
const request2: MetonaRequest = {
  meta: { /* ... */, iteration: 2, requestId: 'r_003' },
  // 消息包含历史 + 工具结果
  messages: [
    { role: 'user', content: '读取 /home/user/data.csv 并分析内容。', timestamp: t },
    { role: 'assistant', content: '', toolCalls: [{ id: 'tc_1', name: 'read_file', args: { file_path: '/home/user/data.csv' }, iteration: 1 }], timestamp: t },
    {
      role: 'tool',
      content: '',
      toolResult: { toolCallId: 'tc_1', toolName: 'read_file', result: '...', success: true, durationMs: 5, timestamp: t,
        summary: '文件 data.csv 包含 1000 行数据，字段为 name,age,email,city' },
      timestamp: t
    },
  ],
  tools: [/* 同上 */],
  params: { stream: true, thinkingEnabled: false },
};

electron/harness/types/
├── metona-request.ts      // MetonaRequest, MetonaMessage, MetonaToolDef 等
├── metona-response.ts     // MetonaResponse, MetonaStreamEvent, MetonaError 等
├── metona-context.ts      // MetonaContext, MetonaSystemPrompt
├── metona-memory.ts       // MetonaMemoryItem
├── metona-tool.ts         // MetonaToolCall, MetonaToolResult
├── metona-adapter.ts      // IMetonaProviderAdapter 接口
└── index.ts               // 统一导出

electron/harness/adapters/
├── base-adapter.ts        // Adapter 基类（共享逻辑）
├── deepseek.adapter.ts
├── agnes-ai.adapter.ts
├── ollama.adapter.ts
# ├── anthropic.adapter.ts    # 未来计划
# └── openai.adapter.ts       # 未来计划